<!html>
<title>Xyzzy About and Help</title>
<style>
body {text-align: justify}
span.opcode {color: purple;}
span.mono {font-family: monospace;}
</style>
<body>
<h1>Xyzzy</h1>

<p>ZCode interpreter for Android &copy; 2014 Addie MacGruer.

<p><small>This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.</small>

 <p><small>This program is distributed in the hope that it will be useful,
    but <strong>without any warranty</strong>; without even the implied warranty of
    <strong>merchantability</strong> or <strong>fitness for a particular purpose</strong>.  See the
    GNU General Public License for more details</small>.

<h2>Contents</h2>
<p><a href="#about">About</a>
<p><a href="#history">Revision History</a>
<p><a href="#preferences">Preferences</a>
<p><a href="#notes">Technical notes</a>
<p><a href="#complete">Games that have been tested to completion</a>
<p><a href="#todo">To-do list</a>
<p><a href="#contact">Contact me</a>

<h2 id="about">About</h2>
<p>I've always been a big fan of interactive fiction (or text adventures, as they were called back in my ZX Spectrum days) and think that
smartphones should be ideal for playing them on the move.  However, the existing interpreters on the Android store all had some feature
that rendered them less than suitable, in my opinion.  Dreadful input (<em>ie.</em> not the Android default on-screen keyboard),
ugly text, inexplicable slowness, a tendency to crash, or some combination of the above, seemed to be common features.  So I set out to write
my own, ensuring that it would crash quickly, at least...

<p>Text adventures being well suited to the limitations of early computers, there were very many released, with a great
number of games implemented on a number of engines across every computer system available.  Reimplementation of engines for every
computer is inefficient, and in order to combat this...

<blockquote><p>The Z-machine was created on a coffee table in Pittsburgh in 1979. It is an imaginary computer
whose programs are adventure games, and is well-adapted to its task, implementing complex
games remarkably compactly. They were still perhaps 100K long, too large for the memory of
the home computers of their day, and the Z-machine seems to have made the first usage of vir-
tual memory on a microcomputer. Further ahead of its time was the ability to efficiently save and
restore the entire execution state.
<p>The design's cardinal principle is that any game is 100% portable to different computers: that is,
any legal program exactly determines its behaviour. This portability is largely made possible by
a willingness to constrain maximum as well as minimum levels of performance (for instance,
dynamic memory allocation is impossible).
<p>Infocom's catalogue continues to be sold and to be played under interpreter programs, either
original Infocom ones or more recent and generally better freeware ones. About 130 story files
compiled by Infocom's compiler Zilch survive and since 1993 very many more story files have
been created with the Inform design system.
<p style="text-align:right">--The Z-Machine Standards Document (Graham Nelson)</p>
</blockquote>

<p>Thanks for downloading my attempt at implementing this imaginary computer.

<p>There are a very large number of games available to download at the IF archive.  See
<a href="http://www.ifarchive.org/indexes/if-archiveXgamesXzcode.html">http://www.ifarchive.org/indexes/if-archiveXgamesXzcode.html</a>.
The ones which end in .z3, .z4, .z5, .z8 or .zblorb will work.  Zip files will need unpacking before play.

<h2 id="history">Revision history</h2>
<ol>
<li>First public release: 24th April 2014.  Probably still full of bugs and surprises, despite my testing.
</ol>
<h2 id="preferences">Preferences</h2>
<ul>
<li><p><strong>Display text size</strong> Changes the size of text in the game selection menu and in games.  Screen width is set at the 
start of each game, on restore, and when you rotate the screen.   If you've set a large font, you might have to do some scrolling to see
everything, some things won't be centered, and <q>quote boxes</q> will look quite ugly.  But at least you'll be able to read it.

<li><p><strong>Enable sound effects</strong> Currently only the two basic beeps are implemented, high and low pitched.
These usually provide feedback on scoring or unrecognised input.

<li><p><strong>Enable colour</strong> Most colour games (<em>eg.</em> Adam Cadre's works) are polite enough to ask before you start,
but it's possible to disable colour entirely, here.  <em>Beyond Zork</em> still looks dreadful, though.

<li><p><strong>Upper screens are monospaced</strong> A lot of games expect the upper screens to be in a <span class="mono">monospaced
font</span>, especially for
printing status lines and quoteboxes, which can appear quite ugly otherwise.  Unfortunately, most of them don't specify the
monospaced font when they start drawing it.  This forces <span class="mono">monospace</span> on for the top windows, regardless of what's chosen.

<li><p><strong>Report minor errors in story files</strong> A number of non-fatal errors can be present in story files, which can
usually be ignored without affecting play.  Usually only useful for story authors while debugging.

<li><p><strong>Length of scroll back</strong> The bottom screen has scrollback enabled.  This number shown is the number of screen
updates which are preserved.  Having too many items eventually slows down the phone, and would eventually lead to memory problems.
50 is about appropriate on my S4, but you might want to increase or decrease this depending on how puissant your device is.

<li><p><strong>Speed of automatic scrolling</strong> I've implemented automatic scroll-forward for when large amounts of text is
displayed.  A setting of about 3 gives the right reading speed for me; might depend on the speed of your device, too.

<li><p><strong>Use 24-hour clock</strong> Version 3 games are either <q>score mode</q> or <q>timed mode</q>.  This chooses whether to
display the time in V3 games with a 24-hour or a 12-hour clock.

<li><p><strong>Run pirated story files</strong> There is a <span class="opcode">@piracy</span> opcode on the Z-Machine, which causes different story file execution
if the game is detected to have been obtained by copyright infringement.  This checkbox is the detection mechanism.  <em>nb.</em> this
is completely useless, and essentially unused in all but demonstration story files.

<li><p><strong>Monitor opcounts and performance</strong> Before text inputs, print a status line showing number of opcodes processed, and
the amount of time spent processing them.  Mainly useful for story authors who want to do a bit of optimisation, me for optimising of
code, or perhaps for some benchmarking of your phone.  Some stories will execute 200k opcodes between inputs, which
is fine on a desktop computer but will lead to a few seconds of lag even on a fast mobile phone -- my S4 can execute about 80k opcodes per
second on a z8 file once the JIT has kicked in.
</ul>
<h2 id="notes">Technical notes</h2>

<p>Some games (eg. <em>Anchorhead</em> while reading books) require cursor key input, which isn't present on (my) Android phone.  There are some
keyboard shortcuts present on the action bar (cursor up/down/left/right, delete, return) that simulate the desired keys.

<p>The z-spec suggests that it would be beneficial to implement the Quetzal save file format, to allow save game exchange between devices
and interpreters.  The spec is biased towards a C-style implementation of callstacks and frame pointers; this implementation uses Java
serialisation for save (and undo) which would make this a pain.  Also, because Xyzzy saves games in its private use area (and thus doesn't
require write privileges), you'd need a rooted device to get to your saves, anyway.

<p>The interpreter claims to support <q>timed input</q>, <em>ie.</em> only allowing you a certain amount of time to type your commands.
It doesn't; that's exceptionally annoying.  Memories of getting killed while playing <em>The Hobbit</em> on the Spectrum aftering
going to the loo and being done in by a wandering warg while away from keyboard still irk, decades later.

<h2 id="complete">Games That Have Been Tested To Completion</h2>
<ul>
<li><p><em>9:05</em> (Adam Cadre)
<li><p><em>A Change In The Weather</em> (Andrew Plotkin)
<li><p><em>CZECh</em>, the comprehensive z-code emulation checker (Evin Robertson and Amir Karger), executes completely and correctly in both z3
and z5 modes.
<li><p><em>The Lurking Horror</em> (Dave Lebling).  No sound, claims <q>restore</q> fails when it works fine.
<li><p><em>Photopia</em> (Adam Cadre)
<li><p><em>Tangle and Web</em> (Andrew Plotkin)
<li><p><em>Wishbringer</em> (Brian Moriarty)
<li><p><em>Zork: The Undiscovered Underground</em> (Marc Blank and Michael Berlyn)
</ul>

<h2 id="todo">To-do list</h2>
<p>The following opcodes are unsupported</p>
<ul>
<li><p><span class="opcode">@throw</span> and <span class="opcode">@catch</span>: using these opcodes will cause a crash.
Unfortunately, the z-code specification doesn't make sense to me. If anyone can drop me a line clearing up (exactly) what these should do,
I'll be happy to work them in.

<li><p><span class="opcode">@sound_effect</span> only implements the standard beeps.  Enjoy the extra feedback scoring points in <em>Trinity</em>.

<li><p><span class="opcode">@input_stream</span> does nothing.

<li><p>The V6 opcodes (drawing pictures, moving windows, detecting the mouse, etc) all do nothing.

<li><p><em>Beyond Zork</em> is hella ugly.  Mind you, I remember it being hella ugly on the Atari, too.T
</ul>

<h2 id="contact">Contact me</h2>
<p>My email contact is <a href="mailto:addiemacgruer@googlemail.com">addiemacgruer@googlemail.com</a> for feedback or queries.

<p>The code is kept at <a href="https://code.google.com/p/xyzzy/">https://code.google.com/p/xyzzy/</a>.  There's a bug tracker on
there, and if you can find where my code is wrong, that would be great.

<p>If you've managed to play another story to completion, then that would be handy to add to the list.

<p>If the interpreter has crashed, or is displaying peculiar behaviour, then it would be helpful to know what game you were playing
(and what you were doing) when it did.  If a stack trace has displayed, then the name of the exception and the top line which starts with
<q>at uk.addie.xyzzy....</q> (including the line number) would be very helpful.